Reading Category Samples#

The Scripting app provides access to category-based health data using the global function Health.queryCategorySamples(). Category samples represent health-related events or states with a start date, end date, and a discrete value — such as sleep stages, mindful sessions, menstrual flow, and ovulation test results.

This guide explains how to query, interpret, and use category samples in your scripts.

What Is a Category Sample?#

A category sample includes:

• type: The category data type (e.g., "sleepAnalysis", "mindfulSession")
• startDate / endDate: The time interval the event occurred
• value: An integer representing a state, mapped from an enum
• metadata: Optional additional info

Examples:

• "sleepAnalysis" with value asleepCore, awake, or inBed
• "menstrualFlow" with value mild, moderate, or severe

API Overview#

1Health.queryCategorySamples(
2  categoryType: HealthCategoryType,
3  options?: {
4    startDate?: Date
5    endDate?: Date
6    limit?: number
7    strictStartDate?: boolean
8    strictEndDate?: boolean
9    sortDescriptors?: Array<{
10      key: "startDate" | "endDate" | "value"
11      order?: "forward" | "reverse"
12    }>
13  }
14): Promise<HealthCategorySample[]>

Parameters#

Example: Reading Sleep Analysis Samples#

1const results = await Health.queryCategorySamples("sleepAnalysis", {
2  startDate: new Date("2025-07-01T00:00:00"),
3  endDate: new Date("2025-07-05T00:00:00"),
4  sortDescriptors: [{ key: "startDate", order: "forward" }]
5})
6
7for (const sample of results) {
8  console.log("Start:", sample.startDate)
9  console.log("End:", sample.endDate)
10  console.log("Sleep State:", sample.value) // Use enum to interpret value
11}

You can map the value to an enum like this:

1const value = sample.value
2
3switch (value) {
4  case HealthCategoryValueSleepAnalysis.awake:
5    console.log("Awake")
6    break
7  case HealthCategoryValueSleepAnalysis.asleepCore:
8    console.log("Asleep (Core)")
9    break
10  case HealthCategoryValueSleepAnalysis.asleepDeep:
11    console.log("Asleep (Deep)")
12    break
13  case HealthCategoryValueSleepAnalysis.inBed:
14    console.log("In bed")
15    break
16  // Handle other states as needed
17}

Example: Reading Mindful Session Events#

1const sessions = await Health.queryCategorySamples("mindfulSession", {
2  startDate: new Date(Date.now() - 7 * 86400 * 1000), // past 7 days
3})
4
5console.log(`Found ${sessions.length} mindful sessions`)

Notes#

• All returned items are instances of HealthCategorySample
• The .value field is numeric and should be interpreted using the appropriate enum
• You can access optional .metadata for extra context if available
• Category data is ideal for modeling sleep, mental wellness, reproductive health, and symptoms

Summary#

To read category samples:

1. Use Health.queryCategorySamples(categoryType, options)
2. Filter by date, sort, and limit as needed
3. Map .value to the correct enum for human-readable interpretation

This API gives you structured access to event-based health records in HealthKit.